本文档面向运维人员,说明如何操作本地域、数据设施、网络设施以及加入联邦。
DomainPrefix-Number 格式,例如 core0-1swapoff -a 并永久移除 /etc/fstab 中的 swap 条目/etc/sysctl.d/hugepages.conf,内容为:vm.nr_hugepages = SIZE
其中 SIZE = HP_Capacity / 2MiB注意:当前 Incus 的内存占用统计只统计 4k 大小的普通页,因此实例使用大页内存时,要额外关注 hugetlb 余量。
Debian 默认开启 THP。对于 JVM,额外添加 -XX:+UseTransparentHugePages 标志显式激活。
openssl req -newkey rsa:2048 -nodes -keyout client.key -x509 -days 3650 -out client.crt -subj "/CN=Common Name"
在本地域节点添加信任证书:
incus config trust add-certificate client.crt
导出 pfx 证书供浏览器使用:
openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt
CLI 连接:
mv client.key client.crt ~/.config/incus/
incus remote add ALIAS IP/NS --accept-certificate
OIDC 鉴权通过添加联邦认证设施(Zitadel)实现。具体配置参考认证设施 endpoint:https://authn.eoelab.org
Incus 使用 OpenFGA 实现基于关系的访问控制(ReBAC)。它不是传统的“角色对应固定菜单”,而是由 Incus 针对每次 API 请求检查:
用户或组 + entitlement + Incus 对象 = 是否允许
例如,为 user:alice 建立 project:dev 的 operator 关系后,Alice 会通过继承获得 dev 项目内资源的操作权限。Incus 实际检查的是 can_view、can_edit、can_exec 等 entitlement,admin、operator、user、viewer 是 entitlement 的权限包。
关系元组使用 OpenFGA 的 user / relation / object 三元组:
| user | relation | object | 含义 |
|---|---|---|---|
user:alice | operator | project:dev | Alice 是 dev 项目的操作员 |
group:ops#member | operator | project:dev | ops 组成员是 dev 项目的操作员 |
user:alice | can_exec | instance:dev/web01 | Alice 只能获得 web01 的命令执行能力 |
关系元组的增删和查询参考 libfga。
所有对象均使用 <类型>:<标识符> 格式。项目级对象的标识符以项目名开头,不是单独的 project/instance_name 参数。
| 对象 | 格式示例 |
|---|---|
| Server | server:incus |
| Project | project:dev |
| Certificate | certificate:<完整指纹> |
| Storage Pool | storage_pool:local |
| Network Integration | network_integration:ovn |
| Instance | instance:dev/web01 |
| Image | image:dev/<完整指纹> |
| Image Alias | image_alias:dev/debian |
| Network | network:dev/br0 |
| Network ACL | network_acl:dev/web |
| Network Address Set | network_address_set:dev/internal |
| Network Zone | network_zone:dev/example.net |
| Profile | profile:dev/default |
| Storage Bucket | storage_bucket:dev/local/archive[/location] |
| Storage Volume | storage_volume:dev/local/custom/data[/location] |
server、project 和 shared_with 是 Incus 维护资源归属关系时使用的结构关系,不应作为普通用户权限手动修改。
can_create_* 不保证创建后还能查看或管理资源。can_edit 通常包含修改、重命名和删除,不是无破坏性的“编辑配置”。can_exec、can_update_state 等专项 entitlement 不会自动获得 can_view。CLI 可能会先查询对象,因此最小权限通常还要搭配 viewer。[user, group#member] 的 relation 可以直接授予用户或组;只有 operator、viewer from project 等计算表达式的 relation 只能通过角色或继承获得。模型表达式示例:
define can_edit: [user, group#member] or operator from project
表示可以把 can_edit 直接授予用户或组,也可以由资源所属 Project 的 operator 自动获得。
Incus 初始化模型时会加入:
server:incus#authenticated@user:*
所以每个已经通过认证的用户即使没有任何业务角色,仍然拥有:
can_view:基本服务器信息和只读集群信息can_view_metrics:进入 metrics 接口,实例指标仍按 Instance can_view 过滤can_view_resources:宿主机 CPU、内存、磁盘和网络资源信息can_view:可以看到存储池,但敏感配置在没有 can_edit 时会被隐藏因此“没有分配角色”不等于完全没有可见信息。
三个作用域中的角色均按以下顺序包含右侧角色:
admin -> operator -> user -> viewer
Server 的同名角色会传递给所有 Project,Project 的同名角色会传递给其所有 Instance。
| 作用域 | 角色 | 实际能力 |
|---|---|---|
| Server | viewer | 查看所有项目及其资源、证书、网络集成和完整 Server config |
| Server | user | viewer + 所有项目的 user,可进入所有实例并访问其数据面 |
| Server | operator | user + 所有项目的 operator,可创建、修改、删除所有项目资源 |
| Server | admin | 完整服务器和集群管理、全局资源创建,并成为所有项目的 admin |
| Project | viewer | 查看该项目及其所有资源 |
| Project | user | viewer + 查看项目 events/operations + 项目内所有实例的 user |
| Project | operator | user + 创建、修改、删除项目资源 + 项目内所有实例的 operator |
| Project | admin | operator + 修改、重命名、删除项目本身及其限制配置 |
| Instance | viewer | 查看一个实例的配置、状态、日志、快照和备份信息 |
| Instance | user | viewer + console、exec、文件、SFTP、NBD 和 TCP 转发 |
| Instance | operator | user + 编辑、删除、启停、重建以及管理快照和备份 |
| Instance | admin | 当前模型中实际能力与 operator 相同,没有额外 entitlement |
需要特别注意:
user 可以进入项目内全部实例并执行命令,但不能启停实例。user 不是低权限只读用户,通常能以实例内部 root 身份执行命令、读写文件或访问磁盘。viewer 不只是查看 Server,它还会得到所有项目的只读权限和完整 Server config。operator 不能修改 Server 本身,但可以操作所有项目中的资源。| Entitlement | 允许的操作 |
|---|---|
can_view | 查看基本服务器信息、集群状态、成员和集群组 |
can_view_sensitive | 查看完整 Server config |
can_view_resources | 查看宿主机资源、Storage Pool resources 和非托管网卡 |
can_view_metrics | 访问 metrics;返回的实例指标继续按 Instance can_view 过滤 |
can_view_privileged_events | 查看 logging 类型的特权事件 |
can_edit | 修改服务器配置,管理集群、成员、集群组、warnings 和内部管理接口 |
can_create_certificates | 添加信任证书 |
can_create_projects | 创建 Project |
can_create_storage_pools | 创建 Storage Pool |
can_create_network_integrations | 创建 Network Integration |
can_override_cluster_target_restriction | Project 禁止指定 Cluster target 时仍允许指定成员 |
| Entitlement | 允许的操作 |
|---|---|
can_view | 查看 Project 和 Project state |
can_edit | 修改限制和配置、重命名、删除 Project,以及查看 Project access |
can_create_instances | 创建实例、复制到该项目、从备份导入实例 |
can_create_images | 导入镜像或从实例发布镜像 |
can_create_image_aliases | 创建 Image Alias |
can_create_profiles | 创建 Profile |
can_create_networks | 创建 Network |
can_create_network_acls | 创建 Network ACL |
can_create_network_address_sets | 创建 Network Address Set |
can_create_network_zones | 创建 Network Zone |
can_create_storage_volumes | 创建、复制或导入 Storage Volume |
can_create_storage_buckets | 创建 Storage Bucket |
can_view_events | 查看该项目的 operation、lifecycle 和 network-acl events;不包含 logging |
can_view_operations | 列出该项目的异步 operations |
| Entitlement | 允许的操作 |
|---|---|
can_view | list/show/info/state,读取日志、metadata、NVRAM、快照和备份信息 |
can_edit | 修改配置、rename/move/migrate/delete、rebuild、恢复快照、修改 metadata/NVRAM |
can_update_state | start、stop、restart、freeze、unfreeze |
can_access_console | 连接 Instance console;读取 console log 只需要 can_view |
can_exec | 在实例中执行命令,并访问 exec output |
can_access_files | pull、push、删除实例文件 |
can_connect_tcp | 使用 incus port-forward 连接实例端口 |
can_connect_nbd | 通过 NBD 访问实例磁盘 |
can_connect_sftp | 通过 SFTP 访问实例文件系统 |
can_manage_snapshots | 创建、修改、重命名和删除快照;恢复快照仍需要 can_edit |
can_manage_backups | 创建、重命名、删除和导出实例备份 |
只希望用户在单个实例内执行命令时,建议授予该 Instance 的 viewer 和 can_exec,不要使用会额外开放 console、文件、NBD、SFTP、TCP 的 user。
| 对象 | can_view | can_edit 或专项权限 |
|---|---|---|
| Certificate | 查看证书信息;只能由 Server viewer 继承 | 修改、替换、删除证书 |
| Image | 查看和下载/导出镜像;Public Image 不受 OpenFGA 限制 | 修改、删除、refresh、生成 secret |
| Image Alias | 查看 Alias | 修改、重命名、删除 |
| Profile | 查看配置和设备 | 修改、重命名、删除 |
| Network | 查看状态、leases、forward、load balancer 和 peer;主 Network config 会被隐藏 | 修改、重命名、删除 Network,并管理其 forward、load balancer 和 peer |
| Network ACL | 查看 ACL 规则 | 修改、重命名、删除 |
| Network Address Set | 查看地址 | 修改、重命名、删除 |
| Network Zone | 查看 Zone 和 records | 修改 Zone,并管理 records |
| Network Integration | 查看信息;只能由 Server viewer 继承,config 会被隐藏 | 修改、重命名、删除 |
| Storage Pool | 所有已认证用户均可查看,config/source 会被隐藏 | 修改和删除;不能限定只查看某个 Pool |
| Storage Volume | 查看状态、bitmap、快照和备份,并可导出 Volume backup | 修改、移动、重命名、删除、重建、恢复快照和修改 bitmap |
| Storage Bucket | 查看 Bucket、备份和 key;读取 key 时会返回 access key 和 secret key | 修改 Bucket,并创建、修改、删除 key |
Storage Volume 还定义了以下专项 entitlement:
| Entitlement | 允许的操作 |
|---|---|
can_access_files | 读取、写入和删除卷内文件 |
can_connect_nbd | NBD 块设备访问 |
can_connect_sftp | SFTP 文件访问 |
can_manage_snapshots | 管理 Volume snapshots |
can_manage_backups | 管理 Volume backups |
Storage Volume 的 can_edit 会自动包含以上所有专项 entitlement。直接授予某个专项 entitlement 时不会自动得到 can_view。
以下 API 资源没有独立 OpenFGA 对象,复用父对象权限:
| 子资源 | 权限所属对象 |
|---|---|
| Instance snapshot、backup、log、metadata | Instance |
| Volume snapshot、backup、bitmap | Storage Volume |
| Bucket key、backup | Storage Bucket |
| Network forward、load balancer、peer | Network |
| Network Zone record | Network Zone |
| Cluster member、cluster group、warning | Server |
| Events、Operations | Project |
Network 是共享资源的特例。Incus 可以使用 shared_with 把 Default Project 的 Network 共享给其他 Project;共享项目的 viewer 只能查看该 Network,不能修改它。
can_view 过滤,因此无权限时经常返回空列表而不是 403。can_view 不允许访问实例文件,但 can_exec、console、NBD 和 SFTP 均属于高敏感数据面权限。can_view 可以导出 Volume backup,不应把它视为仅查看元数据。can_view 可以读取 Bucket key 的 access key 和 secret key,不应把它授予不应接触 Bucket 数据的观察者。| 需求 | 建议关系 |
|---|---|
| 只读一个 Project 的全部资源 | Project viewer |
| 使用一个 Project 的全部实例,但不能启停或改配置 | Project user |
| 管理一个 Project 中的资源,但不能修改 Project 限制 | Project operator |
| 只读一个 Instance | Instance viewer |
| 只在一个 Instance 执行命令 | Instance viewer + can_exec |
| 只启停一个 Instance | Instance viewer + can_update_state |
| 完整管理一个 Instance | Instance operator |
| 只查看或编辑一个普通资源 | 对支持直接授权的 Image、Network、Profile、Volume 等对象授予 can_view、can_edit 或专项 entitlement |
模型没有 deny。如果需要“查看项目中除某实例外的全部资源”,不能先授予 Project viewer 再拒绝该实例,必须逐个授予允许访问的对象。
Incus 官方明确要求:不信任其拥有宿主机 root 权限的用户不得授予以下关系:
server: admin
server: operator
server: can_edit
server: can_create_storage_pools
server: can_create_projects
server: can_create_certificates
certificate: can_edit
storage_pool: can_edit
project: admin
其余关系也必须配合严格的 Project restrictions。尤其是 Project operator,如果项目允许特权实例、宿主机磁盘或设备直通,仍可能影响宿主机。
截至 2026-09-14 的 Incus main(提交 30a4243),Storage Bucket backup API 检查 storage_bucket#can_manage_backups,但 OpenFGA 模型没有为 storage_bucket 定义该 relation。因此当前代码不能正常通过这项授权,不应假设 Bucket backup 管理权限已经可用。升级 Incus 后应重新核对该问题。
模型与 API 映射来源:
service ssh start/usr/sbin/sshd默认不允许在 LXC 中嵌套运行 OCI 容器。容器部署服务可直接以 OCI 实例运行在 Incus 上,并使用 Incus 网络内部通信。例外:CI/CD 中使用 Kaniko 构建 OCI 镜像。
按照 <接口类型>_<介质><容量><性能> 格式命名。
例如 fs_nml:文件系统接口 / NVMe / 1–4T / 性能 l。
Btrfs 接口为 fs,由节点本地提供。
bs,由 TrueNAS 远程提供nasceph-Number(独立集群)fs:多节点读写,适合对 I/O 延迟不敏感的文件读写bs:读写延迟双低,适合数据库os:大数据或海量小文件由于 Incus侧需要一个用户名,而不是sub这种长数字序列,我们在Zitadel添加以下action
function addUsername(ctx, api) {
api.v1.claims.setClaim("preferred_username", ctx.v1.getUser().preferredLoginName);
}
触发器设置为: 自定义令牌 - access 令牌创建前
注意:admin团队已完成此步骤
向admin团队申请,得到一个实例URL+api_token
基于libfga(https://codeberg.org/eoelab/libfga)操作自行设置一个store,得到store id
根据带宽选择方案:
| 带宽 | 方案 |
|---|---|
| 1/2.5G | 电口(RJ45 + CAT6),无 RDMA |
| 10G | 光口(SFP+ + DAC)+ RoCEv2 |
| ≥40G | 光口(QSFP+ + DAC)+ 强制 RoCEv2 |
注意:使用 RoCEv2 需要支持 PFC 和 ECN 的网卡与交换机;光口默认使用 DAC 线,无需光模块。
INTERFACE-Domain172.16.0.0/12eth0;VM 需要 proxy 设备时可设置静态地址:eth0:
ipv4.address: 实例静态ip
network: 接入网络
type: nic
Listen 为外部端口,connect 为内部端口NAT mode 启用,Listen 的 IP 为节点 IP,connect 的 IP 为实例静态 IPblock-host:丢弃主机地址段流量:
block-internal:丢弃内部地址段流量:
申请人需满足以下任一条件:
获得用户权限后,才可以将设备加入联邦。
EOELAB 不支持静默退出。需要退出时向 admin 团队发送退出邮件,admin 团队将执行:
对于本地域,还包括:
长期失联或存在安全风险的节点可能被强制移除。
sudo tailscale up --login-server https://hs.eoelab.org
注意:在云服务器上激活客户端可能导致内部镜像解析到 CGNAT 范围,可换源到公网站点(如 USTC 镜像源)。
tailscale login --login-server https://hs.eoelab.org
services:
derper:
image: ghcr.io/yangchuansheng/derper:v1.98.8
ports:
- 3478:3478/udp
- 12345:12345
environment:
DERP_DOMAIN: example.com
DERP_CERT_DIR: /cert
DERP_ADDR: ':12345'
DERP_STUN_PORT: '3478'
DERP_HTTP_PORT: '-1'
DERP_VERIFY_CLIENTS: "true"
volumes:
- ./cert:/cert
- /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
chn(ISO 3166-1 三字母规范),区域名称使用国家全称注意:不接受自签名节点,必须包含公共 CA 证书;中国大陆云服务器必须使用备案域名作为入口点。
具备公网的本地域/服务设备默认可获得 eoelab.org 子域名。节点本地生成并保存私钥,联邦设施基于 DNS-01 challenge 完成 ACME 验证与证书签发。节点通过唯一身份凭证获取自身被授权域名的证书。
connections:
forgejo:
url: https://codeberg.org/
uuid: UUID
token: TOKEN
forgejo 将替换为申请人的用户名,用于内部区分、避免同名 key 冲突| 维度 | 取值 |
|---|---|
| size | tiny(2–4G)、small(4–8G)、medium(8–16G) |
| arch | amd64、riscv64 |
| runtime | lxc(标准)、vm(全功能) |
[purpose],例如 mirror:位于海外,同步中国大陆无法访问的 OCI 镜像/软件包| 用途 | endpoint | 框架 |
|---|---|---|
| 数据源 | VictoriaMetrics | |
| 可视化 | Grafana | |
| 日志 | VictoriaLogs | |
| 告警 | Alertmanager |
DomainPrefix-Number 格式<接口>_<介质><容量><性能>sudo tailscale up --login-server https://hs.eoelab.org